---
title: "Generate Artifacts"
description: "Learn how to generate and return artifacts like images and structured data."
---

Artifacts are specialized message parts that represent named outputs like files, images, or structured data. Unlike regular text responses, artifacts have a `name` field that allows consuming applications to implement specific handling semantics—such as offering downloads, displaying rich content, or enabling iterative workflows.

Common use cases for artifacts include:

- **Generated files**: Reports, images, or documents created by your agent
- **Structured data**: JSON, CSV, or XML for programmatic consumption
- **Rich media**: Images, charts, or visualizations
- **Download assets**: Files that users can save locally

Refer to the [Message Structure](/core-concepts/message-structure#artifact) documentation for detailed artifact specifications.

This guide demonstrates how to generate common artifact types like images and JSON data within your ACP agent.

## Generating Image Artifacts

Agents can generate images dynamically and return them as artifacts. This example uses the Pillow (PIL) library to create a simple PNG image, encode it in base64, and yield it as an `Artifact` message part.

```python pil_image.py
import base64
import io
from collections.abc import AsyncGenerator

from acp_sdk.models import Message, Artifact
from acp_sdk.server import Context, RunYield, RunYieldResume, Server
from PIL import Image, ImageDraw

server = Server()


@server.agent()
async def pil_image_generator(
    input: list[Message], context: Context
) -> AsyncGenerator[RunYield, RunYieldResume]:
    """Generates a simple PNG image using PIL and returns it."""
    img = Image.new("RGB", (100, 100), color="red")
    draw = ImageDraw.Draw(img)
    draw.text((10, 10), "ACP Image", fill="white")

    buffer = io.BytesIO()
    img.save(buffer, format="PNG")
    buffer.seek(0)

    yield Artifact(
        name="image.png",
        content=base64.b64encode(buffer.read()).decode("utf-8"),
        content_encoding="base64",
        content_type="image/png"
    )


server.run()
```

Key points:
- Images must be base64 encoded for inline transmission
- Set `content_encoding="base64"` for binary data
- Always handle potential image generation errors
- The content is saved to a `BytesIO` buffer
- An `Artifact` is yielded with `name`, `content` (base64 string), `content_encoding="base64"`, and `content_type="image/png"`.

## Generating JSON Artifacts

Agents can also return structured data, like JSON, as artifacts. This is useful for providing machine-readable output alongside or instead of human-readable text.

```python json_artifact.py
import json
from collections.abc import AsyncGenerator

from acp_sdk.models import Message, Artifact
from acp_sdk.server import Context, RunYield, RunYieldResume, Server

server = Server()


@server.agent()
async def json_artifact_generator(
    input: list[Message], context: Context
) -> AsyncGenerator[RunYield, RunYieldResume]:
    """Generates a JSON artifact."""
    data = {
        "status": "success",
        "result": {
            "item_id": 123,
            "description": "Sample JSON data"
        }
    }

    yield Artifact(
        name="result.json",
        content=json.dumps(data, indent=2),
        content_type="application/json"
    )


server.run()
```

Key points:
- A Python dictionary (`data`) holds the structured information.
- `json.dumps()` converts the dictionary into a JSON string.
- An `Artifact` is yielded with `name`, `content` (the JSON string), and `content_type="application/json"`.
- The default `content_encoding` is `"plain"`, which is suitable for JSON strings.

By generating artifacts, your agents can provide rich, structured outputs beyond simple text, enabling more sophisticated interactions and integrations.
